MacFormat 1995 March

home *** CD-ROM | disk | FTP | other *** search

/ MacFormat 1995 March / macformat-022.iso / Shareware City / Utilities / MacDOS™ 2.0.0ƒ / User's Guide / 13.4 REN - TOUPPER < prev next >

Wrap

Text File | 1994-11-23 | 29.3 KB | 780 lines | [TEXT/ttxt]

REN, RENAME change the name, the creator, and the type of a file or group of files. These commands also assign the current date/time and toggle the 'hidden' file attribute. Syntax ren source [destination] [/!] [/C=src creator] [/C!dst creator] [/D] [/H] [/L] [/T=src file type] [/T!dst file type] The two commands REN and RENAME are functionally identical. Parameters source is a filename preceded by an absolute or relative path which specifies the file or group of files to be renamed. A group of files is identified via a wildcarded filename or a directory name. To rename a folder rather than its contents, refer to RENDIR. destination is a filename which specifies the new name[s]. If omitted, it is assumed to be identical to the source argument. Switches /! enables automatic update of destination names in case of duplications. When RENAME finds that a file with the same name already exists, it extends the new filename with an alphanumeric character (0..9, a..z). /C=src creator /C!dst creator with the equal sign, /C specifies that only files of a particular creator are to be renamed. With the exclamation mark, it specifies that the creator of the file[s] is to be changed to the specified value. Note that no spaces are allowed on either side of the equal sign or exclamation mark, and that the creator must be four characters long. Therefore, if a creator includes space characters you must double quote the switch (eg. ren /c=ABCD "/c=ABC " would select all files in the current directory created by 'ABCD'and change their creator to 'ABC '). /D changes the date and time of last update to the current date and time. /H toggles the 'hidden' file attribute. A hidden source becomes visible, and a visible source becomes hidden. This switch is only legal when the source argument specifies a single file. /L makes the selection of source files case sensitive. /T=src file type /T!dst file type with an equal sign, /T specifies that only files of a particular type (eg. 'TEXT') are to be renamed. With the exclamation mark, it specifies that the type of the file[s] is to be changed to the specified value. Note that no spaces are allowed on either side of the equal sign or exclamation mark, and that the file type must be four characters long. Therefore, if a file type includes spaces, you must double quote the switch (eg. ren /t=ABCD "/t=ABC " would select all files in the current directory of type'ABCD'and change their type to 'ABC '). MacDOS vs DOS destination DOS returns an error if the destination is identical to the source. MacDOS accepts equal filenames, although it only performs the renaming when necessary. The main reason for relaxing the check is that MacDOS provides the possibility of changing some file attributes without having to change the filenames. Switches MacDOS provides several switches while DOS provides none. Usage of wildcards MacDOS has a better wildcarding mechanism than DOS (see below for details). Notes Upper and lower case Unless you specify the option /L, characters in upper and lower case are considered identical when filtering source files. On the other hand, with or without /L the new destination filename will be as typed by you. Note that because the Mac OS does not make distinction between upper and lower case when identifying files, a command which just changes from upper to lower case or vice versa a single filename without actually changing characters returns the error "duplicate filename". You must perform such a change in two steps or use wildcards. Changing visibility You are only allowed to change the visibility of one file at a time. That is, you cannot wildcard the filename when you use /H. Wildcarding strategies MacDOS memorises adjacent wildcard characters as a single wildcard sequence characterised by the minimum and maximum lengths of possible matching strings. The minimum length of a matching string coincides with the number of question marks in the sequence. The maximum length of a matching string also coincides with the number of question marks but only if there are no asterisks. If there are one or more asterisks, the maximum length of a matching string is only limited by the maximum length of filenames (31 characters). Note that because of this strategy, wildcarding strings containing at least one asterisk and having the same number of question marks are equivalent (eg. "*?*?", "**??", "?*?", "?****?**", etc). In fact, there is no reason to use more than one asterisk in a string of adjacent wildcard characters, and the ordering of the question marks and the single asterisk is irrelevant. When you specify a folder as source parameter, MacDOS renames all the files in that folder. Normally, each wildcarding section of the destination consists of a single asterisk, as the main function of RENAME is to replace fixed parts of source filenames with fixed strings which appear in the destination. That is, MacDOS only uses the wildcards in the destination to match corresponding wildcard sections in the source. Therefore, wildcard sequences in the destination usually have a maximum length equal to or greater than the corresponding sequences in the source. Nevertheless, combinations with a wildcard sequence in the destination shorter than the corresponding one in the source are legal. In that case, the source string is truncated before being inserted into the destination. For example, "REN *.* ????????.???" cuts all filenames containing a period to eight characters before and three characters after the period. Names with fewer characters than the maximum length of the wildcarding sequences in the destination are left unchanged. If, on the other hand, the minimum length of a wildcarding sequence in the destination is greater than the number of characters matched by the corresponding sequence in the source, the characters are copied to the destination filename WITHOUT padding or repetitions. In conclusion, "REN *.txt ???.doc" renames a.txt to a.doc, ab.txt to ab.doc, and abcd.txt to abc.doc . The renaming with wildcarding sections in the destination shorter than the corresponding sections in the source is somewhat dangerous, because different filenames might end up with the same name. Examples When the source contains AS MANY wildcard sections as the destination, they are matched in sequence. The characters explicitly given in the source are then replaced by the corresponding characters of the destination: no wildcards: REN b.ext blob renames 'b.ext' to be 'blob' one wildcard section: REN *TXT *DOC replaces all terminating "TXT"s with "DOC"s REN ??? *.TXT attaches the extension ".TXT" to all filenames three letters long REN aFold bla_* "bla_" is prepended to all filenames in the folder 'aFold' REN abc* * "abc" is removed from all filenames which begin with it two wildcard sections: REN *LOW* *low* replaces with "low" all sequences which match "LOW" first encountered in each filename (ie. "Low", "low", "LoW", etc.) REN *LOW* *low*/L replaces with "low" the "LOW" first encountered in each filename REN "* ???" *.* replaces a space with a period in all filenames where the space occurs three characters before the end REN *.?* ????????.* truncates to eight characters before the period all filenames which contain a period followed by at least one character REN *AA* *A* replaces the first pair of 'A's found in each filename with a single 'A'. What happens if there are two files named, say, XAAAB and XAAB ? MacDOS aborts the operation when it attempts to rename XAAAB, because XAAB already exists. REN/! *AA* *A* as in the previous example, MacDOS replaces the first pair of 'A's found in each filename with a single 'A'. If there are two files named, say, XAAAB and XAAB, MacDOS renames XAAAB to XAAB0 because XAAB already exists (although later XAAB is renamed to XAB). If XAAB0 already exists, MacDOS renames XAAAB to XAAB1 (although later XAAB0 is renamed to XAB0). This "forced" renaming continues by changing 1 to 2, 3, ..., 9, a, b, ..., and z. When the source contains MORE wildcard sections than the destination, the parts masked in the source by the additional wildcarding sections are left unchanged. This is a way of selecting filenames on the basis of several specific strings but then only replace the first one. For example: REN SRC*.* DST* replaces the first three characters of filenames which contain a period somewhere after the initial sequence (equivalent to: "REN SRC*.* DST*.*") REN *.?? *.X inserts an 'X' after the period of filenames in which the period is followed by exactly two characters (equivalent to: "REN *.?? *.X*") REN * Z prepends a 'Z' to all filenames (equivalent to: "REN * Z*") The source is NOT ALLOWED to contain FEWER wildcarding sections than the destination. The following example illustrates the problems which can occur when truncating filenames: REN A*X A?X cuts down to three characters all filenames which begin with an 'A'. What happens if two files are named, say, AB1X and AB2X ? AB1X is renamed to ABX, but then the renaming sequence must be aborted, because AB2X should also be renamed to ABX and that is not allowed. With the option /!, AB2X would be renamed to ABX0. Frequently occurring errors E27: File or directory not found The source parameter did not identify any file at all or one of the folders specified in the path could not be found. Note that creator and file type are case sensitive. Therefore, /T=text does not find any file of type 'TEXT'. E58: Duplicate filename(s) A file with the destination filename (or one of the filenames, in case of wildcarded renaming) already existed. There are two cases in which this error message can also be displayed when the /! switch is ON: 1 The new name is already 31 characters long and MacDOS cannot append the character which would make it unique. 2 MacDOS has already encountered 36 files with the same new name. In this case, MacDOS has run out of possible extension (10 digits and 26 letters). See Also RENDIR RENDIR changes the name of a single directory. Syntax rendir source destination Parameters source specifies the directory to be renamed. It can be preceded by a volume and path spec. destination specifies the new name of the directory. It cannot be preceded by a volume and path spec. MacDOS vs DOS DOS does not support RENDIR. Frequently occurring errors E11: Not a directory You tried to rename a file with RENDIR. Use RENDIR. E27: File or directory not found MacDOS did not find the folder to be renamed or one of the folders specified in its path. See Also MKDIR, RMDIR, RENAME RESTART restarts the Macintosh. Syntax restart MacDOS vs DOS DOS does not support RESTART. See Also SHUTDOWN SERIAL Directs MacDOS to use the serial port[s] for Input/Output. Syntax serial [inout | OFF] [/M] Parameters inout identifies the ports to be used for serial communication. It consists of a pair of letters (not case sensitive) which specify the ports to be used for input and output respectively. 'A' indicates port A (the modem port), 'B' indicates port B (the printer port) and '@' indicates that no port should be used. OFF disables I/O via the serial port[s]. /M specifies that MacDOS has just to Monitor the characters read from the serial port instead of interpreting them as commands. The default is that MacDOS does accept commands from the serial port. Without parameters, SERIAL reports the current setting. MacDOS vs DOS DOS does not support SERIAL. Notes Port settings The ports are set to 9600 bps, no parity, 8 data bits, 1 stop bit, and hardware handshaking. Working in parallel to the standard I/O The console window and the keyboard remain fully operational while I/O via the serial port[s] is enabled. Control characters MacDOS accepts from the serial ports the following control characters: cntl-C Aborts the current operation. cntl-H Backspace, deletes the last character typed. cntl-I Attempts to complete file and folder names. cntl-M Terminates a command and starts its execution. cntl-Z EOF, used in conjunction with MORE to store text into a file. Testing a port The small utility program SendToPort provided on the MacDOS floppy (in the folder serial comms) sends characters to a serial port and can be used to test a particular setup. You can also use SendToPort to control a copy of MacDOS on a different system: connect the two Macs via a serial port (eg. the modem port), start SendToPort on the "master" Mac and direct it to use port A, then start MacDOS on the "slave" Mac and type at the MacDOS prompt the following command: "serial a@". This will direct the "slave" to accept commands via the modem port without replying. You will then be able to control the "slave" remotely by typing on the "master" commands like: dir^m confirm on^m You will also be able to abort "slave" operations by typing on the "master" the two characters ^C . For additional information on SendToPort, please refer to the README file in the same folder. Examples SERIAL AA /M sets both input and output to the modem port. MacDOS then sends to the port all characters displayed in the console window and displays on the console window all characters received from the same port. SERIAL BA sets the input to the printer port and the output to the modem port. MacDOS then sends to the modem port all characters displayed in the console window and accepts characters from the printer port as if they had been typed on the keyboard. SERIAL BA sets the input to the modem port and disables the output. MacDOS then accepts characters from the modem port as if they had been typed on the keyboard but does not send any character to either serial port. Frequently occurring errors MacOS Error -97 The port is in use. Use the other port if you can. AppleTalk could be the culprit. SET displays, sets, and removes global variables. Syntax set [var=[value]] Parameters var is the name of the variable to be SET. If you omit var, SET displays the list of variables with their values. value is the string to be assigned to the variable. When you omit value, SET behaves in different ways depending on the type of variable: system variables are re-initialised to their defaults, while user-defined variables are removed altogether. MacDOS vs DOS SETting of system variables When you set the system variables PROMPT, DIRCMD, and PATH to an empty string, MacDOS sets them to their default values, while DOS removes them. Spaces and variable names MacDOS ignores the spaces between the variable name and the equal sign, while DOS does not. The result is that DOS creates variables with names which terminate with one or more spaces. For example, DOS responds to the command "set var =3" by setting a variable named "var " rather than simply "var"! MacDOS also replaces multiple spaces and tabs within a variable name with single spaces. As MacDOS uses the equal sign to delimit the variable name, you must not double quote variable names. Notes Spaces after the equal sign The variable is SET to whatever follows the equal sign, including any space. Therefore, "set var = a " sets a variable named "var" to " a ". Variable names The names are not case sensitive and are actually saved by MacDOS in upper case. If you use double quotes in variable names, you run into trouble when you try to do something with those variables, because in all other commands the double quotes are used to delimit names and are not considered to be part of the names themselves. This anomaly of SET was introduced to be consistent with DOS. Examples set a numeric var = 33 set ZZZ=strings do not need to be enclosed in double quotes set prompt= See Also INCR, DECR, TOUPPER, SSTR, PATH, PROMPT, DIR SHIFT moves the replaceable parameters of a batch program forward one position. Syntax shift MacDOS vs DOS The two implementations are identical. Notes SHIFT allows you to execute batches with more than 9 user- defined replaceable parameters (the current maximum is 24). After MacDOS has executed the command SHIFT, the replaceable parameter 0 contains what was previously in 1, 1 contains what was in 2, etc. The last replaceable parameter (ie. 9) contains what you typed as 10th parameter of the batch program and was previously unaccessible. By using SHIFT repeatedly, you gain access to all the strings you typed after the batch name when you started the program. This is particularly useful if you need to perform the same operation on all parameters. In that case: 1 Write the code for %1. 2 After performing the operation the first time, execute SHIFT and re-execute the code from the beginning. The new %1 will then contain what during the initial pass was in the second parameter. 3 Repeat the same sequence several times until you find that %1 is empty. Examples This batch uses SHIFT to process all replaceable parameters, one at a time: :LOOP_LBL if "%1x" == x goto END_LBL perform on %1 the required task ... shift goto LOOP_LBL :END_LBL SHOW retrieves the message corresponding to an error code. Syntax show err [var] Parameters err is the error code var is the name of the variable where SHOW is requested to store the message. If var is omitted, SHOW displays the message on the screen. If MacDOS does not "know" an error code, SHOW just displays the error code itself. MacDOS vs DOS DOS does not support SHOW. Notes Additional parameters SHOW ignores additional parameters. SHOW, DOSERR, and ONERROR SHOW is particularly useful to implement your own error handling in a batch program, especially when executing with ECHO OFF. You can trap errors with ONERROR, jump to a fixed command line, and then use the system variable DOSERR to decide what action is necessary. Also, you can use the command SHOW %DOSERR% to display error messages in clear: ! setup error trapping onerror ERR_LBL ! setup return label set RET =LBL_1 set DOSERR=0 ! *** here insert the command for which you want *** ! *** to trap the error *** :LBL_1 ... goto DONE_LBL :ERR_LBL error-handling procedure if %DOSERR% == ... show %DOSERR% ! reset error trapping and resume normal execution onerror goto %RET% :DONE_LBL come here to terminate the batch program Examples show 27 returns the string File or directory not found show 333 returns the string 333 show %var1% var2 the rest of the line is ignored stores into var2 the error message corresponding to the code stored in var1 show abcd efgh ijkl sets the variable efgh to the string abcd See Also ONERROR SHUTDOWN shuts down the Macintosh. Syntax shutdown MacDOS vs DOS DOS does not support SHUTDOWN. See Also RESTART SSTR extracts SubSTRings from variables. Syntax sstr var [delim] [/E] [/L | /R] Parameters var is the name of the variable from which the substring is to be extracted. SSTR replaces the content of var with the substring. delim is the string which delimits the substring. MacDOS searches var and stops when it finds delim. Depending on the presence of switches, MacDOS extracts from var the substring on the left or on the right of delim. If you omit delim or delim is empty, MacDOS leaves var unchanged. MacDOS aborts the command and reports an error when var does not contain delim. Switches /E searches var from the End (ie. from right to left). When /E is omitted, the search is done from the beginning (ie. from left to right). /L | /R specifies whether the substring is to be extracted on the Left or on the Right of delim. If you omit both /L and /R, /L is assumed. If you include in the command both /L and /R, the command is rejected. MacDOS vs DOS DOS does not support SSTR. Notes Upper and lower case Searches are always case sensitive. If you need to perform a case-insensitive search, convert first var and delim to uppercase with TOUPPER. Examples set var=a few chars and nothing more sstr var "and nothing" var now contains: "a few chars " sstr var /E " " var now contains: "a few chars" sstr var w /R var now contains: " chars" sstr var a /L var now contains: " ch" Frequently occurring errors E72: String search failed the string delim could not be found within var. See Also SET, INCR, DECR, TOUPPER SUBSTVOL creates a literal volume ID. Syntax substvol letter vol Parameters letter is a character between 'A' and 'Z' (case insensitive). letter can then be used in place of vol in all commands. vol is a volume identifier (1 is the start-up volume). Note that the volume does not need to be mounted. MacDOS vs DOS DOS does not support SUBSTVOL. Notes SUBSTVOL was introduced to make the porting of batch programs from DOS easier by allowing you to use letters instead of numbers when identifying volumes. See Also VOL TIME displays and sets the system time and the time format. MacDOS uses the format set through TIME whenever it needs to display a time (starting a LOG file, in a DIR listing, etc.). Syntax time [time] Parameters time is the time which should become the new system time. Also, the format of the new time becomes the new format used by MacDOS whenever it displays a time. If you type midnight (ie. 00:00:00a for a 12h format and 24:00:00 for a 24h format), MacDOS only updates the time format and leaves the system time unchanged. If you omit time, MacDOS displays the current system time in the current format and prompts you for a new time. You can then type the new time, or hit Carriage Return if you do not want to change anything. MacDOS vs DOS DOS does not let you change the clock format via the command TIME. Notes 12h vs. 24h clocks To change between 12h and 24h clock formats, you only need to type a time in the new format. The best way of doing it is to include in autoexec.bat the setting of midnight. By default, time is displayed in 24h format with colons as separators. Partial time specification You can omit to specify the seconds or both minutes and seconds. In that case, MacDOS sets the missing fields to zero. Note that a time specification cannot terminate with a separator. Therefore, times like 17:20 and 18 are legal, while 17:20: and 18: are not. Also, you cannot omit intermediate fields. Therefore, times like 16::45 and :20:30 are illegal. Examples command old time new time time 00:00.00 16:03:20 16:03.20 time 00:00.00 04:03:20p 04:03.20p time 00:00.00a 16:03:20 04:03.20p time 00:00.00a 04:03:20p 04:03.20p time 24;00;00 16:03:20 16;03;20 time 24;00;00 04:03:20p 16;03;20 time 17:20/03 16:03:20 17:20/03 time 17:20/03 04:03:20p 17:20/03 time 08-15-30 16:03:20 08-15-30 time 08-15-30a 16:03:20 08-15-30a time 17 16:03:20 17:00:00 time 17:7 16:03:20 17:07:00 time 17:7 04:03:20p 17:07:00 Frequently occurring errors E52: Invalid time Probably one of the fields was outside its valid range. See Also DATE TOUPPER converts variable contents to uppercase. Syntax toupper var Parameters var is the name of the variable to be converted. TOUPPER replaces the string contained in var with its uppercase version. MacDOS vs DOS DOS does not support TOUPPER. Notes Diacritical marks TOUPPER converts strings with the standard function provided by the Macintosh Toolbox. Therefore, characters with diacritical marks are converted to uppercase correctly (ü to Ü, ö to Ö, etc.). See Also DECR, INCR, SSTR